//*************************************************************************************
/** \file stl_profiler.h
 *    This file contains a class which measures the speed at which functions run. It
 *    keeps basic statistical information so it can calculate the mean, slowest, and 
 *    fastest run times measured during repeated runs of a function. 
 *
 *  Revisions:
 *    \li 12-18-2009 JRR Original file
 *
 *  License:
 *    This file copyright 2009 by JR Ridgely. It is released under the Lesser GNU
 *    public license, version 2. 
 */
//*************************************************************************************

/// These defines prevent this file from being included more than once in a *.cc file
#ifndef _STL_PROFILE_H_
#define _STL_PROFILE_H_

#include "base_text_serial.h"				// Header for serial devices
#include "stl_timer.h"						// Header for time measurement class
#include "global_debug.h"					// Header for serial device debugging


//-------------------------------------------------------------------------------------
/** This class implements a very simple execution-time profiler. It measures how long
 *  a function takes to run, again and again, then makes available some very simple
 *  statistical information about the run times. 
 */

class stl_profiler
{
	protected:
		task_timer& the_timer;				///< The timer which measures real time
		time_stamp maximum;					///< Maximum time function took to run
		time_stamp minimum;					///< Time for the quickest function run
		time_stamp average;					///< Stamp holds recently computed average
		time_stamp run_sum;					///< Sum of measured function run times
		uint32_t runs;						///< Number of runs that have been measured
		time_stamp start_time;				///< Time at which measurement was started

	public:
		stl_profiler (task_timer&);			// Constructor just allocates memory
		void clear (void);					// Clear statistical data items
		void start (void);					// Begin a measurement run
		void end (void);					// End a measurement run and record times

		// This method returns the duration of the longest recorded run of the code
		// which is being profiled. 
		const time_stamp& get_maximum (void);

		// This method returns the duration of the shortest recorded run of the code
		// which is being profiled. 
		const time_stamp& get_minimum (void);

		// This method returns the average duration of all the runs of the code which
		// is being profiled. 
		const time_stamp& get_average (void);

		/** This method returns the number of runs of the target code which have been
		 *  measured in the current sample set.
		 *  @return The number of runs which have been measured
		 */
		uint32_t get_num_runs (void) { return (runs); }
};

// This overloaded operator prints profiler data to a serial device
base_text_serial& operator<< (base_text_serial&, stl_profiler&);

#endif // _STL_PROFILE_H_
